Skip to content

feat(blaze)!: remove legacy instance routes - #2585

Merged
WeissonHan merged 1 commit into
alibaba:mainfrom
WeissonHan:feature/blaze/sandbox-api-compat-draft
Aug 17, 2026
Merged

feat(blaze)!: remove legacy instance routes#2585
WeissonHan merged 1 commit into
alibaba:mainfrom
WeissonHan:feature/blaze/sandbox-api-compat-draft

Conversation

@WeissonHan

@WeissonHan WeissonHan commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

Description

Blaze exposes sandbox lifecycle and guest operations only through /v1/sandboxes.

Blaze has not been released with a /v1/instances compatibility contract, so this change removes that HTTP namespace completely. Production routing contains no instance-namespace matcher or compatibility handler, and the long-lived documentation describes only the current sandbox routes. There is also no special regression test or response-precedence guarantee for the removed namespace; ordinary unregistered paths are handled by the server's general routing behavior.

The supported routes are:

  • GET /v1/sandboxes
  • POST /v1/sandboxes
  • GET /v1/sandboxes/{id}
  • DELETE /v1/sandboxes/{id}
  • POST /v1/sandboxes/{id}/exec
  • POST /v1/sandboxes/{id}/read
  • POST /v1/sandboxes/{id}/write

Action-style reset, checkpoint, and destroy routes are not registered under the sandbox namespace. Canonical destruction remains DELETE /v1/sandboxes/{id}. Checkpoint capture and listing are delivered separately by #2472.

Existing JSON field names such as instance and instance_id, and the storage.instances_dir configuration key, remain unchanged because they describe data and storage rather than an HTTP namespace.

The change also removes the incomplete reset handler, the placeholder checkpoint handler, and server-state accessors that became unused with those handlers. Strict Clippy verifies that the resulting production code has no warnings or dead-code allowances introduced by this change.

Behavior before

  • Lifecycle and guest operations were registered under both /v1/sandboxes and /v1/instances.
  • The instance namespace exposed incomplete reset and placeholder checkpoint behavior.
  • Documentation presented both namespaces to users.

Behavior after

  • /v1/sandboxes is the only documented and registered management namespace.
  • Sandbox create, list, get, delete, exec, read, and write retain their existing status codes and resource effects.
  • Unsupported sandbox action routes remain unregistered.
  • No production or test code assigns special semantics to /v1/instances.
  • Checkpoint support can add its sandbox routes without preserving a second namespace.

Related issue

Closes #2577

Related checkpoint work: #2444, #2472

This pull request is based directly on current main and does not depend on #2293, #2296, or #2471.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Code refactoring
  • Performance improvement
  • Other

Scope

  • Core
  • SDK
  • Blaze
  • Documentation
  • Build/CI
  • Other

Testing

Revision identity

  • Public head: 8ec393c95aed8fb12f02583af4d6634160272f2a
  • Head tree: 35fe2a74cc8575b75b654a6a9fa673e882662aad
  • Parent and recorded main: 160297392b5f129dabd5accd6dd13214528832d5
  • GitHub merge candidate: ce61858523bb1f527461429f7f7791f5a593dd46
  • Merge candidate parents: 160297392b5f129dabd5accd6dd13214528832d5, 8ec393c95aed8fb12f02583af4d6634160272f2a
  • Merge candidate tree: 35fe2a74cc8575b75b654a6a9fa673e882662aad

The public head and GitHub merge candidate are byte-identical source trees.

Linux validation

Validated on Linux x86_64 with Rust and Cargo 1.88, locked dependencies, offline Cargo access, a fresh source tree, a fresh Cargo home, and separate empty target directories for every major stage:

  • cargo fmt --all -- --check
  • locked metadata with default and all features
  • workspace all-target builds with default and all features
  • strict Clippy with default and all features
  • serial workspace tests: 299 default and 314 all-feature tests passed
  • strict rustdoc with default and all features
  • repository documentation lint and link checks
  • 8/8 exact sandbox-route, request-body, guest-operation, and response-boundary tests
  • source tree and final Git tree unchanged after validation

Evidence archive SHA-256: b23a24206685304507a090bf770b1baca5abb9ca805c4c4e3b5510a821f1c9b4.

Hosted Blaze, documentation, website, commit-message, pull-request metadata, component, and CLA checks passed for the exact head. Codex reviewed 8ec393c95a and found no major issues. This pull request is ready for maintainer review.

Documentation

The English and Chinese Blaze README, user guide, and lifecycle design describe only the current /v1/sandboxes API. No migration note or version-log entry is included because Blaze has not been released with the removed namespace.

@WeissonHan
WeissonHan requested a review from casparant August 15, 2026 15:04

Copy link
Copy Markdown
Collaborator Author

@codex review Please verify the sandbox handler separation and confirm that /v1/instances remains a behavior-preserving compatibility layer. Review exact head 3bcf1afee00787cd119258f97af61f6ca21a57f3; this is a provisional Draft stacked only on #2290.

@github-actions github-actions Bot added component:blaze src/blaze scope:documentation ./docs/|./*.md|./NOTICE labels Aug 15, 2026
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 3bcf1afee0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@WeissonHan

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: 3bcf1afee0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@WeissonHan
WeissonHan marked this pull request as ready for review August 16, 2026 13:25

@qoderai qoderai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

本次修改清晰区分 /v1/sandboxes 规范命名空间与 /v1/instances 兼容层,并收紧 warm pool 与重置路径的语义边界。以下三点建议供进一步确认:

  1. reset 接口在文档中声明“运行中实例返回 501 且不改变状态与资源”,建议在 blazed 层明确约束,以避免未来实现只重置部分资源时破坏兼容承诺。
  2. [pool] 兼容配置仅接受旧版打包默认值,示例策略文件已移除该段,建议在 README 中强调任何手工 [pool] 修改都会被拒绝或忽略,以降低运维误用风险。
  3. storage_pool.quarantined 当前始终为零且 warm pool 逻辑已移除,建议在设计文档中明确该字段仅用于报告暂时不可清理槽位,并提醒监控侧不要将其视作可用容量。

🤖 Generated by QoderView workflow run

@WeissonHan
WeissonHan marked this pull request as draft August 16, 2026 14:52
@WeissonHan
WeissonHan force-pushed the feature/blaze/sandbox-api-compat-draft branch 4 times, most recently from a2579e7 to e044518 Compare August 16, 2026 15:15
@WeissonHan WeissonHan changed the title refactor(blaze): separate sandbox API handlers feat(blaze)!: remove legacy instance routes Aug 16, 2026

Copy link
Copy Markdown
Collaborator Author

@codex review Please review exact head e044518dcbcff8475072b269a7087962078187ef and the complete diff from current main. Focus on removal of every /v1/instances route, the 404-without-state-change boundary, preservation of the seven /v1/sandboxes operations and existing JSON fields, removal of incomplete reset/checkpoint handlers and dead state accessors, and the English/Chinese migration documentation. Please report any P1 or P2 issue.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e044518dcb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/blaze/crates/blazed/src/api.rs
@WeissonHan
WeissonHan force-pushed the feature/blaze/sandbox-api-compat-draft branch 2 times, most recently from 39f5d98 to e46b17f Compare August 16, 2026 15:57

Copy link
Copy Markdown
Collaborator Author

@codex review Please review exact head e46b17f25183f18d0500e7efb192036e36c9f0ee and the complete diff from current main. Focus on rejecting every /v1/instances request before body collection, preserving 404 precedence without lifecycle, runtime, or storage side effects, retaining the seven supported /v1/sandboxes operations and existing JSON fields, removing the incomplete reset/checkpoint handlers and dead state accessors, and keeping the English/Chinese migration documentation accurate. Please report any P1 or P2 issue.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e46b17f251

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/blaze/README.md Outdated
@WeissonHan
WeissonHan force-pushed the feature/blaze/sandbox-api-compat-draft branch from e46b17f to e0ebb10 Compare August 16, 2026 16:19

Copy link
Copy Markdown
Collaborator Author

@codex review Please review exact head e0ebb106b963ba4784c0daba7a3370b1ddf3e508 and the complete diff from current main. Focus on removal of every /v1/instances route, rejection before request-body collection with no lifecycle, runtime, or storage side effects, preservation of the seven supported /v1/sandboxes operations and existing JSON fields, removal of incomplete reset/checkpoint handlers and dead state accessors, and consistent English/Chinese migration documentation. Please report any P1 or P2 issue.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: e0ebb106b9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@WeissonHan
WeissonHan marked this pull request as ready for review August 16, 2026 16:54
@WeissonHan
WeissonHan force-pushed the feature/blaze/sandbox-api-compat-draft branch from e0ebb10 to 6ddaa71 Compare August 17, 2026 02:30
Expose lifecycle and guest operations only under /v1/sandboxes. Remove
compatibility routing, long-lived documentation, and special rejection
handling for the former /v1/instances namespace because Blaze has not been
released with that contract.

Remove the reset and placeholder checkpoint handlers together with their
now-unused server-state accessors. Keep existing JSON field names and
storage.instances_dir unchanged; they are not HTTP namespace compatibility.
Checkpoint capture follows separately.

Signed-off-by: Weisson <Weisson@linux.alibaba.com>
@WeissonHan
WeissonHan force-pushed the feature/blaze/sandbox-api-compat-draft branch from 6ddaa71 to 8ec393c Compare August 17, 2026 02:32
@WeissonHan

Copy link
Copy Markdown
Collaborator Author

@codex review Please review exact head 8ec393c95aed8fb12f02583af4d6634160272f2a and the complete diff from current main. Verify that /v1/sandboxes is the only registered and documented management namespace, that no /v1/instances matcher, compatibility handler, or specialized negative test remains, that the seven supported sandbox operations keep their existing behavior, that the incomplete reset and checkpoint handlers and unused state accessors are removed, and that the retained JSON field names and storage.instances_dir configuration are not mistaken for HTTP compatibility. Please also check the English and Chinese documentation for consistency and report any P1 or P2 issue.

@WeissonHan

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 8ec393c95a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@WeissonHan
WeissonHan merged commit 1bef887 into alibaba:main Aug 17, 2026
27 checks passed
@WeissonHan
WeissonHan deleted the feature/blaze/sandbox-api-compat-draft branch August 17, 2026 03:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component:blaze src/blaze scope:documentation ./docs/|./*.md|./NOTICE

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove legacy instance routes from the Blaze API

2 participants